\section{Cookbook for Raspberry Pi}


There is a collection of bash scripts in the `raspberry\_scripts`-directory of the `raspberry-utils`-repository that make recurring tasks easieer. They use programs that were installed during the installation from the quick-start guide.\\

Following a short overview. The sections after will explain, how to use them.

\paragraph{download\_bin.sh}: Downloads the latest core- and firmware files from the repository. The core-file in the repository always contains the newest firmware for the RISC-V cpu. The files will be downloaded to a sub-directory `bin/`. 

\paragraph{upload\_core.sh}: Uploads the core (volatile) to the FPGA. 

\paragraph{flash\_core.sh}: Flashs the core-file into the QSPI flash (non-volatile).

\paragraph{flash\_erase.sh}: Erases the QSPI flash (completely!)

\paragraph{start\_xvc\_server.sh}: Starts the Virtual Cable Server. The VCS is a software replacement for a real USB-Xilinx JTAG programmer. Vivado's hw\_server can connect to the Virtual Cable Server and use it as JTAG interface to the FPGA. There are no restrictions, that means, everything a USB JTAG programmer supports also is supported using the Virtual Cable Server. This also includes security relevant settings like bitstream-encryption, eFUSE registers ,...

\paragraph{upload\_riscv.sh}: Uploads a RISC-V firmware to the soft-cpu. The core-file already comes with the latest firmware but it could be necessary to upload another firmware to the RISC-V.

\paragraph{start\_debugger.sh}: Starts the OpenOCD debugger for the RISC-V soft-cpu (the FPGA has to be configured beforehand). The guide in \ref{eclipsedbugging} explains, how to setup a development environment for the firmware and how to use the debugger from within Eclipse.

\paragraph{start\_serial.sh}: Starts the `picocom` serial terminal. If jumpered correctly on the development board \ref{devboard}, the serial terminal can be used to transmit and receive data to and from the FPGA-module through the `/dev/ttyS0` serial device*.

*: `/dev/ttyS0` has to be enabled via `raspi-config`


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



\subsection{Uploading the CryptoCore program}
\label{xsvfpi}
\textbf{Prerequisites:  Raspberry Pi quickstart \ref{quickstart}, Jumper J9 (FPGA) on ``PI'' \ref{jumpers}}\\

The CryptoCore program is included in XSVF files, which contain `recordings` of JTAG communication.

These files were generated in Vivado and can be replayed on the Raspberry Pi.\\

There are two XSVF files in the repository.

\paragraph{`iccfpga-utils/raspberry\_scripts/bin/iccfpga\_spi\_flash.xsv`}: XSVF for flashing the Core into the QSPI-flash. The flash gets automatically erased before flashing.
\paragraph{`iccfpga-utils/raspberry\_scripts/bin/iccfpga\_fpga.xsv`}: XSVF for uploading the Core to the FPGA. This only is temporary until the next power-cycle. \\

Both XSVF files are automatically generated by the build script described in \ref{generateall}\\

For convenience there are two scripts, one for flashing the core:

\begin{lstlisting}[language=bash]
cd ~/iccfpga-utils/raspberry
sudo ./flash_core.sh
\end{lstlisting}

the other for uploading the core to RAM:

\begin{lstlisting}[language=bash]
cd ~/iccfpga-utils/raspberry
sudo ./upload_core.sh 
\end{lstlisting}

The difference is that the second script only temporarily - until the next power-cycle - uploads the core to the FPGA without touching the QSPI flash. 



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%




\subsection{Starting the Virtual Cable Server}
\label{cableserver}
\textbf{Prerequisites: Raspberry Pi quickstart \ref{quickstart}, Jumper J9 (FPGA) on ``PI'' \ref{jumpers}}\\

The Virtual Cable Server (VCS) is an alternative to using a USB Xilinx JTAG adapter to flash bitstreams onto the CryptoCore, using a Raspberry Pi 3/4.

\begin{lstlisting}[language=bash]
cd ~/iccfpga-utils/raspberry
sudo ./start_xvc_server.sh
\end{lstlisting}

Output:
\begin{lstlisting}[language=bash]
Virtual Cable Server startet

To connect vivado to the server use <some-ip>:2542
\end{lstlisting}

Now you can connect Vivado with the VCS as desribed in \ref{vivadoxvcs}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



\subsection{Starting the OpenOCD debugger for RISC-V}

\textbf{Prerequisites: Raspberry Pi quickstart \ref{quickstart}, Jumper J9 (FPGA) on ``PI'' \ref{jumpers}}\\

The OpenOCD debugger can be used for remote debugging. A local instance is started and an Eclipse installation on a PC can connect to the debugger for debugging the firmware.

\begin{lstlisting}[language=bash]
cd ~/iccfpga-utils/raspberry
sudo ./start_debugger.sh
\end{lstlisting}

\subsection{Uploading the Firmware}

\textbf{Prerequisites: Raspberry Pi quickstart \ref{quickstart}, Jumper J9 (FPGA) on ``PI'' \ref{jumpers}}\\

Although the XSVF files already include the firmware, it is possible to temporarily upload custom firmware to the CryptoCore. 

\begin{lstlisting}[language=bash]
cd ~/iccfpga-utils/raspberry
sudo ./upload_riscv.sh
\end{lstlisting}

The firmware is started automatically.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\subsection{Opening a Serial Terminal}

\textbf{Prerequisites: Raspberry Pi quickstart \ref{quickstart}, Jumper J7 \& J8 on ``PI'' \ref{jumpers}}\\

To test the RS232 API, you need to open a serial interface on the Raspberry Pi, using certain parameter.

To open a serial terminal with these parameters, do the following:

\begin{lstlisting}[language=bash]
cd ~/iccfpga-utils/raspberry
./start_serial.sh
\end{lstlisting}

This command runs a script, which opens a piocom serial terminal. You can close the terminal by pressing \textbf{CTRL+A} + \textbf{CTRL+Q}.


